package omq.xml;

import omq.xml.element.OMQXmlElement;

import org.w3c.dom.Document;
import org.w3c.dom.Element;


/**
 * Author : Ofer Misk
 * Date   : 18/06/2007
 * This is the XML parser utility 
 */
public interface OMQIXmlUtil {
	/**
	 * Gets an XML file and creates a DOM object from it
	 * @param filePath - the full path of the xml file.
	 */
	public void parseXmlFile(String filePath);
	/**
	 * This method gets a string representation of an xml, and parse it as a document. 
	 * @param xmlString - the xml string
	 */
	public void parseXmlString(String xmlString);
	/**
	 * Parsing the document.
	 * Good use - create an object from each section and save it in an arrayList.
	 * Bad use - print it to console.
	 * The user must implement this method if he needs to parse the XML file 
	 * (naturally he/she does)
	 * @return - XmlElement root and its children
	 */
	public Object parseDocument();
	/**
	 * Another implementation of parseDocument().
	 * Gets the dom object itself to manipulate.
	 * @param dom - The DOM object
	 * @return - XmlElement root and its children
	 */
	public Object parseDocument(Document dom);
	
	/**
	 * And another implementation of parseDocument().
	 * Gets a String representation of an xml and parse it into a dom object,
	 * and then returns the java xml element to the caller.
	 * @param xml - the xml String representation
	 * @return - XmlElement root and its children
	 */
	public Object parseDocument(String xml);
	/**
	 * I take a xml element and the tag name, look for the tag and get
	 * the text content
	 * i.e for <employee><name>John</name></employee> xml snippet if
	 * the Element points to employee node and tagName is 'name' I will return John
	 * @param ele - the xml element
	 * @param tagName - the elements tag name
	 */
	public String getTextValue(Element ele, String tagName);
	/**
	 * Calls getTextValue and returns a int value
	 * @param ele - the xml element
	 * @param tagName - the elements tag name
	 */
	public int getIntValue(Element ele, String tagName);
	/**
	 * This method adds a single element and its children to the xml document
	 * @param element - The element to add
	 * @param parent - The xml Element under it we will place the new element.
	 */
	public void addElementToRoot(OMQXmlElement element,Element parent);
	/**
	 * This method creates the DOM object with a root element given by the user
	 * @param rootElementName - The xml file root element's name
	 */
	public void createDocument(String rootElementName);
	/**
	 * This method creates an empty DOM object.
	 */
	public void createDocument();
	/**
	 * This method appends the root element (and all its children) to the DOM object
	 * and closes the document.
	 */
	public void closeDocument();
	/**
	 * This method writes the DOM object into a file.
	 * @param filename - The requested file name (full path).
	 */
	public void writeXmlToFile(String filename);
	/**
	 * This abstract method will be implemented on the concrete class, extending the 
	 * AXmlUtil abstract class (that implements this interface)
	 * @param e - the element to create object from
	 */
	public abstract Object handleElement(Element e);
	
	public String getDocumentAsString();
}
